﻿// -------------------------------------------------------------------------
//    @FileName         :    NFCacheDataLoadTrans.h
//    @Author           :    Gao.Yi
//    @Date             :    2025-08-14
//    @Email			:    445267987@qq.com
//    @Module           :    NFCacheDataLoadTrans
//    @Desc             :    缓存数据加载事务基类声明
//                           提供缓存数据查询的统一接口，支持批量/单条查询操作
//                           作为子事务处理存储服务器交互，完成后回调父事务
//
// -------------------------------------------------------------------------

#pragma once

#include "NFComm/NFObjCommon/NFTransBase.h"
#include "NFServerTypeDefine.h"

/**
 * @class NFCacheDataLoadTrans
 * @brief 缓存数据加载事务基类（共享内存事务对象）
 *
 * 职责：
 * - 处理缓存数据的查询操作（批量/单条）
 * - 管理存储服务器的交互流程
 * - 支持查询结果的自动缓存更新
 * - 完成后回调父事务处理结果
 *
 * 使用流程：
 * 1. 由父事务创建并初始化此子事务
 * 2. 调用 LoadCacheDataBatchReq() 或 LoadCacheDataSingleReq() 发起查询
 * 3. 处理存储服务器返回的查询结果
 * 4. 将查询到的数据添加到缓存中
 * 5. 完成后回调父事务的 HandleTransFinished()
 *
 * 设计特点：
 * - 支持批量查询和单条查询两种模式
 * - 提供完整的错误处理和事务管理
 * - 支持父子事务的嵌套调用和结果回调
 * - 可扩展的查询结果处理机制
 */
class NFCacheDataLoadTrans : public NF_OBJECT_TEMPLATE_MACRO(NFCacheDataLoadTrans, EOT_CACHE_DATA_LOAD_TRANS_OBJ, NFTransBase)
public:
    /**
     * @brief 构造函数
     *
     * 根据共享内存管理器的创建模式选择初始化方式：
     * - EN_OBJ_MODE_INIT：冷启动模式，调用 CreateInit() 进行完整初始化
     * - 其他模式：热启动模式，调用 ResumeInit() 进行恢复初始化
     */
    NFCacheDataLoadTrans();

    /**
     * @brief 析构函数
     *
     * 销毁 NFCacheDataLoadTrans 对象并释放资源。
     */
    ~NFCacheDataLoadTrans() override;

    /**
     * @brief 创建初始化
     *
     * 用于对象的创建时初始化操作。
     *
     * @return 0 表示成功，其他值为错误码
     */
    int CreateInit();

    /**
     * @brief 恢复初始化
     *
     * 用于对象的恢复时初始化操作。
     *
     * @return 0 表示成功，其他值为错误码
     */
    int ResumeInit();

public:
    /**
     * @brief 初始化运行期参数
     * 
     * 设置事务执行所需的基本参数，通常在创建事务后立即调用
     * 
     * @param serverType 目标存储服类型
     * @param roleId      目标ID（单条场景）
     * @param tableId    表ID
     * @param transId    上层批量事务ID
     * @return 0 表示成功
     */
    int Init(int serverType, uint64_t roleId, int tableId, int transId);

public:
    /**
     * @brief 处理存储服返回消息
     *
     * 根据命令类型分发处理不同的存储服务器响应消息：
     * - NF_STORESVR_S2C_SELECT：批量查询结果
     * - NF_STORESVR_S2C_SELECTOBJ：单条查询结果
     *
     * @param pSsMsgRes 指向存储服务器返回的 Protobuf 消息对象的指针
     * @param cmd       消息命令类型
     * @param tableId   表ID
     * @param seq       消息序列号
     * @param errCode   错误码
     * @return 0 表示成功，其他值为错误码
     */
    int HandleDBMsgRes(const google::protobuf::Message* pSsMsgRes, uint32_t cmd, uint32_t tableId, uint32_t seq, int32_t errCode) override;

    /**
     * @brief 事务结束回调处理
     *
     * 当当前事务完成时，通过上层批量事务ID找到父事务并回调结果。
     * 这是事务链式调用的关键环节，确保批量操作能够正确汇总结果。
     *
     * @param iRunLogicRetCode 运行逻辑返回码
     * @return 0 表示成功，其他值为错误码
     */
    int HandleTransFinished(int iRunLogicRetCode) override;

public:
    /**
     * @brief 批量查询请求
     *
     * 虚函数，子类应重写此方法实现具体的批量查询逻辑。
     * 基类实现仅输出警告信息，提醒开发者需要在子类中实现。
     *
     * @param vecId    包含查询目标ID的向量
     * @param enReason 查询原因
     * @return 0 表示成功，其他值为错误码
     */
    virtual int LoadCacheDataBatchReq(const std::vector<uint64_t>& vecId, int enReason);

    /**
     * @brief 单条查询请求
     *
     * 虚函数，子类应重写此方法实现具体的单条查询逻辑。
     * 基类实现仅输出警告信息，提醒开发者需要在子类中实现。
     *
     * @param ullId    查询目标ID
     * @param enReason 查询原因
     * @return 0 表示成功，其他值为错误码
     */
    virtual int LoadCacheDataSingleReq(uint64_t ullId, int enReason);

    /**
     * @brief 单条查询请求（带 Protobuf 数据）
     *
     * 此方法用于发起单条查询请求，并附带一个 Protobuf 数据对象作为额外参数。
     * 子类应重写此方法以实现具体的查询逻辑。
     *
     * @param ullId 查询目标的唯一标识 ID
     * @param enReason 查询原因/场景标识
     * @param stPbClass 附加的 Protobuf 数据对象，包含查询所需的额外信息
     * @return 0 表示成功，其他值为错误码
     *
     * @note 基类实现仅输出警告信息，提醒开发者需要在子类中实现。
     */
    virtual int LoadCacheDataSingleReq(uint64_t ullId, int enReason, const google::protobuf::Message& stPbClass);
public:
    /**
     * @brief 批量查询返回处理
     *
     * 虚函数，子类应重写此方法实现具体的批量查询结果处理逻辑。
     * 基类实现仅输出警告信息，提醒开发者需要在子类中实现。
     *
     * @param pRes    指向存储服务器返回的查询结果对象
     * @param errCode 错误码
     * @return 0 表示成功，其他值为错误码
     */
    virtual int LoadCacheDataBatchRes(const NFrame::storesvr_sel_res* pRes, int32_t errCode);

    /**
     * @brief 单条查询返回处理
     *
     * 虚函数，子类应重写此方法实现具体的单条查询结果处理逻辑。
     * 基类实现仅输出警告信息，提醒开发者需要在子类中实现。
     *
     * @param pRes    指向存储服务器返回的查询结果对象
     * @param errCode 错误码
     * @return 0 表示成功，其他值为错误码
     */
    virtual int LoadCacheDataSingleRes(const NFrame::storesvr_selobj_res* pRes, int32_t errCode);

protected:
    /** @brief 调用原因/场景标识 */
    int m_iReason;
    /** @brief 操作对象ID */
    uint64_t m_ullRoleId;
    /** @brief 目标存储服务器类型 */
    int m_iServerType;
    /** @brief 数据表ID */
    int m_iTableId;
    /** @brief 上层批量事务ID，用于回调时定位父事务 */
    int m_iTransId;
    /** @brief 目标对象ID */
    uint64_t m_ullTargetId;
};
